\chapter{Źródła danych}
\label{cha:zrodlaDanych}
Poniższy rozdział opisuje dostępne źródła danych, z których można czerpać
informacje dotyczące wydarzeń.\\
Przeprowadzono rekonesans w sprawie dostępnych zewnętrznych platform, z których
można wyłuskiwać informacje dotyczące utworzonych wydarzeń konkursowych.
Wybrano dwie najpopularniejsze platformy, na których użytkownicy mają możliwość
tworzenia konkursów : 

\begin{itemize}
\item Facebook - \url{www.facebook.com}\cite{fbApi}
\item Twitter - \url{www.twitter.com}\cite{twitterDoc}
\end{itemize}

Każda z nich dostarcza SDK programistom, udostępniajac swoje API. W aplikacji
wykorzystano głównie komunikację klient-serwer na bazie stylu
architektury oprogramowania Representational State Transfer(REST)
\cite{restInPractice}.

\section{Facebook}
Facebook dostarcza dla programistów potężne narzędzie zwane Graph API
\cite{fbApi}, które pozwala na transfer danych między Facebookiem a klientem
tegoż API. Jest niskopoziomowym komponentem http bazującym na systemie zapytań.
Działanie przebiega na podstawie komunikacji żądanie-odpowiedź, a~więc
preparowania odpowiednich zapytań. W odpowiedzi dostajemy dane w postaci obiektów - węzłów. 
W Systemie Rozstrzygania Konkursów Internetowych wykorzystano wersję Graph API
2.2, która posiada interfejs zorientowany obiektowo, w przeciwieństwie do wersji
1.x bazującej na strukturalnym stylu programowania\cite{fbApi}.

\subsection{Połączenie}

W celu integracji aplikacji z Facebook'iem należy poczynić kilka kroków, aby
udało się wykonać jakiekolwiek zapytania do Graph API.

\subsubsection{Stworzenie aplikacji Facebook'owej}
Pierwszym krokiem jest stworzenie aplikacji deweloperskiej na Facebooku. Jest to
niezbędne, gdyż dla niej będzie generowany token.

\subsubsection{Tokeny}

Tokeny dostępu są łańcuchami znaków, które identyfikują aplikację i mogą zostać
wykorzystane do wywołań Graph API. Są tymczasowym niezbędnym narzędziem
gwarantującym bezpieczeństwo. Facebook SDK dostarcza kilka
typów tokenów:

\begin{itemize}
\item User Access Token - najczęściej wykorzystywany token - otrzymywany jest
podczas okna dialogowego logowania.
\item App Access Token - modyfikuje i odczytuje ustawienia aplikacji. Może
służyć publikacji akcji Open Graph. Jest generowany podczas konfiguracji
aplikacji.
\item Page Access Token - podobny token do User Access Token, lecz gwarantuje
dostęp do zapisu, odczytu danych należących do strony. Otrzymać go można przez
Graph API.
\item Client Token - jest to token, który można osadzić w aplikacjach
desktopowych lub kodzie binarnym mobilnej aplikacji natywnej. Nie jest
utajniony oraz posiada sporo ograniczeń.

\end{itemize}

\subsubsection{Proces generowania tokenów}

Aby uzyskać token należy wykonać
zapytanie metodą GET do Facebook'a(Rys. \ref{fig:zapytanieOToken}):

\begin{figure}[ht!]
\includegraphics[scale=1.0]{token_otrzymanie}
\caption{Zapytanie o token}
\label{fig:zapytanieOToken}
\end{figure}

Teraz aplikacja może dowolnie korzystać z Graph API. Otrzymanego sekretnego
tokenu aplikacji nie należy udostępniać nikomu, ponieważ jest to prywatny
łańcuch znaków przeznaczony tylko dla niej\cite{fbApi}. Każda platforma posiada
różne API do generowania tokenów, jednak wszystkie działają na podstawie jednej
strategii zaprezentowanej na Rys. \ref{fig:strategiaTworzeniaTokenu}.
 

\begin{figure}[ht!]
\includegraphics[scale=1.0]{generowanie_tokenow}
\caption{Strategia tworzenia tokenu}
\label{fig:strategiaTworzeniaTokenu}
\end{figure}

 


\subsection{Dostępne SDK}

Facebook dostarcza następujące oficjalne SDK:

\begin{itemize}
\item Facebook SDK for iOS
\item Facebook SDK for Android
\item Facebook SDK for Unity
\item Facebook SDK for JavaScript
\item Facebook SDK for PHP
\item Facebook Ads SDK for PHP
\end{itemize}

oraz wiele nieoficjalnych, w tym dla języka Java:

\begin{itemize}
\item Java (Spring) - Spring Social
\item Java (Blackberry) - RIM
\item Kinvey - Kinvey
\item RestFB - Mark Allen
\end{itemize}

W celach obarczenia  odpowiedzialnością losowania serwer, a nie
klienta wykorzystano w aplikacji nieoficjalne rozwiązanie RestFB.

\subsection{Możliwości API}

Graph API jest reprezentacją informacji składającą się z:

\begin{itemize}
\item Węzłów - obiekty takie jak użytkownik, zdjęcie itd
\item Krawędzi - połączenia między obiektami
\item Pól - informacji na temat obiektów takie jak np. data urodzenia
użytkownika
\end{itemize}

Graph API dostarcza wszelkie informacje za pomocą metod HTTP GET oraz POST,
które są wymierzone w serwer graph.facebook.com\cite{fbApi}.
Posiadając identyfikator danego węzła, czy połączenia można budować
najróżniejsze zapytania. Przykładowe żądanie zostało przedstawione na
Rys.\ref{fig:przykladoweZapytanie}



\begin{figure}[ht!]
\includegraphics[scale=1.0]{przykladowe_zapytanie_fb}
\caption{Przykładowe zapytanie do Graph API}
\label{fig:przykladoweZapytanie}
\end{figure}

\section{Twitter}

Twitter posiada kilka pakietów programistycznych, które pozwalają na
wykorzystywanie jego zasobów\cite{twitterMakice}.
\begin{itemize}
  \item Fabric - modularny zestaw narzędzi programistycznych ''Kits'' 
  \item Twitter for Websites - zestaw osadzalnych widget'ów oraz narzędzi
  przeznaczonych dla skryptów
  \item Cards - służy wyświetlaniu dodatkowych danych razem z Tweet'em
  \item OAuth - narzędzie do autoryzacji oraz uwierzytelniania
  \item REST APIs - programistyczny dostęp do zapisu oraz odczytu danych z
  Twitter'a
  \item Streaming APIs - służy do nasłuchiwania na zdarzenia Twitterowe i
  reagowanie na nie
  \item Ads API - służy integrowaniem aplikacji z reklamami
  \item MoPub - zaawansowane narzędzie do integracji aplikacji z reklamami
\end{itemize}
 
 W aplikacji ze względu na ograniczenia dotyczące przesyłania danych nakładane
 przez Twitter zamiast streaming API wykorzystano REST API. 
 
\subsection{Połączenie}

Przed możliwością wykorzystania Twitter API należy poczynić kilka kroków, aby
udało się wykonać jakiekolwiek zapytania.

\subsubsection{Stworzenie aplikacji na Twitterze}
Pierwszym krokiem do wykonania jest stworzenie aplikacji na Twitterze w celu
uzyskania niezbędnych kluczy autoryzacyjnych.
 
\subsubsection{Tokeny}

Aplikacja dostarcza cztery wygenerowane klucze

\begin{itemize}
  \item Consumer Key (API Key)
  \item Consumer Secret (API Secret)
  \item Access Token
  \item Access Token Secret
\end{itemize}

Wszystkie są wykorzystywane w aplikacji klienckiej używającej Twitter API.

\subsubsection{OAuth}

Twitter API v1.1 dostarcza dwie formy uwierzytelniania:

\begin{itemize}
  \item Application-user - jest to powszechna forma uwierzytelniania.
  Sygnowane Żądanie identyfikuje aplikację mając dodatkowo prawa dostępu do wykonywania 
  zapytań w kontekście użytkownika do którego należy token dostępu.
  \item Application-only - jest to forma uwierzytelniania, gdzie aplikacja
  wykonuje żądania w swoim imieniu bez kontekstu użytkownika. Ten sposób zezwala
  na mniejsze ograniczenia dotyczące wykorzystywania zasobów niż forma
  Application-user, wszak niektóre API nie posiadają dla niego
  wsparcia.
\end{itemize}

\subsection{Dostępne SDK}


Twitter dostarcza programistom dwa SDK : 

\begin{itemize}
\item Hbc - klient dla języka Java przeznaczony dla Stream API
\item Twitter-kit-android - wielomodułowy projekt zawierający TweetComposer,
TwitterCore i TweetUI
\end{itemize}

Powstało wiele nieocifjalnych bibliotek dla różnych języków programowania. Jedną
z nich jest Twitter4J stworzona przez człowieka sygnującego się
pseudonimem ''yusuke''.

Cechy biblioteki Twitter4J:
 
\begin{itemize}
  \item Stworzona w 100\% w  języku Java dla JRE $>$ 1.5
  \item Nie posiada dodatkowych zależności do innych projektów
  \item Wspiera OAuth
  \item Kompatybilna z Twitter API 1.1 
\end{itemize}

W projekcie wykorzystano wersję Twitter4J 4.0.4, działającą na licencji Apache
License 2.0.

\subsection{Możliwości API}

Wykorzystane w aplikacji REST API  posiada wiele ograniczeń dotyczących wykonywanych żądań GET dla danego
token'u.
Interwałem czasowym jest 15 minut, po którym pula startuje od nowa
\cite{twitterMakice}.
Różne URL posiadają inne ograniczenia. 
\\Przykładowo zapytanie GET o pozostały limit:
\url{application/rate_limit_status} zezwala na 180 zapytań, lecz już dla wyłuskania retweet'ów:
\url{statuses/retweets/:id}
liczba ta wynosi tylko 60. Dla URL wyszukujących, tzn. zawierających w adresie
\url{/search/} i formy uwierzytelniania Application-user liczba zapytań wynosi
180, zaś dla Application-only jest to 450.
W przypadku przekroczenia tego limitu zapytanie zwraca kod 429
''Too many Requests''.
\\Zapytania są wykonywane pod adres \url{https://api.twitter.com/1.1/}. 
Przykładowe zapytanie wyłuskujące najnowsze tweety: 
\url{https://api.twitter.com/1.1/search/tweets.json}.

